ASP Monthly 1996 June/The Official ASP CD-ROM (June 1996).iso/bbsvend/readme.dat

Text File | 1996-01-09 | 6KB | 141 lines

~TL README Utility - (C) 1995-96 FormGen Inc.  ~BT 95
@C@B Introduction

The @EFormGen README Utility @Eis a very small and fast README file viewer
that supports a number of user configurable text formatting and display
options to jazz up your README files.

All color values and attributes used by README are controlled from within the
readme text file itself, no external configuration file is required.  There
are two basic sets of options, those that control color attributes and the
title that appears on the top line of your screen, and those that affect the
display of various lines of text.

By default, README loads a formatted text file named README.DAT.  If not
found, it searches for a README.TXT file.

@C@BTitle and Colors


The title and color values can only appear on the top line of the README.DAT
file.  The basic format is a tilde character (~) plus a two character code.
These codes are not case sensitive.  When README scans the file, it extracts
and processes these codes on the top line, but never actually displays the
line itself.  The following options are available :

    @E~TL@E    Title on the top line of the screen.

    @E~TN@E    Color of the top and bottom lines.

    @E~TH@E    Color of highlighted text on the top line.

    @E~DV@E    Color of the divider line at the top and bottom of the screen.

    @E~NT@E    Normal text color.

    @E~BT@E    Bold text color.

    @E~ET@E    Emphasized text color.

    @E~FK@E    Function key color.

All colors are entered as a standard combined attribute value, for example 23
for grey text on a blue background etc.

To create, for example, a top line for a program named 'DingBat Solitaire',
with a header and footer color of white on red, a title highlight of bright
white on red, function key colors of bright yellow on red, and a bold text
color of bright red on a blue background, the top line would read :

@C@E ~TL DingBat Solitaire ~TN71 ~TH79 ~FK78 ~BT28

In this example, we have separated the various switches and settings with
spaces for clarity, although this not required by README.  If you want to see
what this example looks like, just edit this README.DAT file, copy this
sample line to the top line of the file, and then run README.  A somewhat
tasteless example, but one that gets the points across !!

Be aware that if the utility is run on a monochrome system, any color values
entered on the top line will be ignored and README will use its own defaults.
Also, any colors that are not set on the top line will assume README's
default values.


@C@BText Processing

There are two types of text processing commands, text formatting and color
attributes.  The various text processing commands should appear at the
beginning of a line of text.  This is not manditory, but it does help the
legibilty of the text file.

The color attribute commands can appear at the begining of a line, or used as
markers to highlight a word or phrase.  The only rule is that only one color
attribute can be used on a single line.  If you are highlighting a phrase,
only one pair of color attributes can appear on a single line.

The basic format of these options is an (@) symbol plus a one character
code.  Once again, these codes are not case sensitive.

    @E@ L@E     Left Justify line.

    @E@ R@E     Right Justify Line.

    @E@ C@E     Center Line.

    @E@ B@E     Paint line or phrase in bold color.

    @E@ E@E     Paint line or phrase in emphasized color.

In the above listing, the space between the (@) symbol and the letter key is
there only to prevent wild justification of the above lines.  If you
inadvertently place both an @ E and a @ B code on the same line, then the
first attribute will be used for the line, and the others will appear within
the displayed text.

When formatting text for use with README, a line should not contain more than
78 characters of text, excluding the embedded codes.  README automatically
removes its own codes and then truncates the balance to 78 characters.

When assigning color attributes, a single attribute at the begining of a line
tells README to paint the entire line in the appropriate color.  A pair of
matching color attributes tells README to paint only the text delimited by
the markers.


@C@BText Output

You may wish to enable your customers to print out the README.TXT file
supplied with your software.  If they printed the supplied file, it would of
course include all of the formatting and color codes.  The README utility
therefore provides a Text Output function assigned to the [Enter] key.

When a user presses [Enter], the contents of the text buffer are written out
to an ASCII text file called README.OUT, in the same format as displayed on
their screen.  The only difference is that no attributes are assigned to
allow their printer to print bold text etc..  A beep is sounded to confirm
the output to the text file.

An error message will appear on the bottom line of the screen if there is no
room on the disk for the new file, or the media is unwritable (for example if
README is run on a CD-ROM).


@C@B Odds and Sods

The README utility display a page number in the upper right corner of the top
line.  This is actually a screen page number intended to provide the user
with a rough idea of where they are in a potentially long text file.

If a file name is not added to the command line when you start README, the
utility first searches for a README.DAT file, the default formatted text
file.  If README.DAT does not exist in the current directory, then README
goes looking for an alternate file named README.TXT.  If this file is not
found, then a message saying 'File Not Found' will appear and you will return
to the DOS prompt.  The README.DAT file provides a way for you to supply a
formatted text file for your application that a user would not likely try to
load into an editor or viewer of some sort.

If README has any problem opening the README.DAT or README.TXT files, or
creating the README.OUT file, then it will immediately quit back to DOS.